FishMarket 1.0

home *** CD-ROM | disk | FTP | other *** search

/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 326-350 / disk_333 / multiplot / docs / multiplot.doc < prev next >

Wrap

Text File | 1992-05-06 | 28KB | 627 lines

MULTIPLOT XLNb This is program placed in the Public Domain for free use WITH THE SPECIFIC EXCEPTION OF REDISTRIBUTION FOR PROFIT. February 1990 Walter & Eliza Hall Institute, c/o PostOffice, Royal Melbourne Hospital, Parkville 3053. VICTORIA This is the second release of Multiplot XLN. It is expected to receive distribution via Fred Fish. If you notice any repeatable bugs or have any suggestions for improvement of enhancement, please send them to me at the address below. This release does not includes the Plt: device. The Plt: device is required to print plots on any workbench supported printer. The Plt: device was distributed with the version of Multiplot found on Fish Disk 292. CHANGES SINCE LAST VERSION Bug fix: Plot dimensions were not reset if a plot was redrawn without text. Bug fix: The function of the REDRAW menu option was not always consistent. Bug fix: Y Axis text was not cleared properly if a plot was redrawn without text. Bug fix: The ZOOM option will no longer crash if used with enthusiasm. The maximum zoom possible is 1,600 times. Bug fix: Multiplot is now a little more resistant to low chip memory situations. Bug fix: The wait pointer was not cleared after cancelling a save in IntroCAD or Draw format. Bug fix: Saves in mCAD, introCAD and Draw format with the grid option switched on did not save the vertical grid lines. Bug fix: The lowest tick or grid line was sometimes omitted. Bug fix: The screen was munged if the ZOOM box or SLIDE vector were drawn using the cross hairs. Bug fix: Multiplot will now handle greater than 20 data sets. As far as I know, the number of data sets is limited by memory alone. Typo fix: The menu option SAVE HPGL is now correctly named. Was HPLG! Style Change: The "How to Plot" window has been renamed DEFINE PLOT and the menu option that calls it has been renamed REDEFINE PLOT. Style Change: The Menu QUIT selection key shortcut has been changed to Left-Amiga-e so as not to conflict with Commodore- Amiga's style guidelines. The menu option has been renamed EXIT so as to remain easy to remember. Style Change: The ZOOM and SLIDE functions now operate in the standard Amiga way; that is, the zoom box or slide vector is drawn WHILE the left mouse button is held down. The screen is redrawn when the left mouse button is released. Style Change: Delimiters (caps) are now drawn on the error bars. This slows some functions down, especially conversions to other formats, but most other graph plotting programs have them, so I put them in. Removal of feature: Menu selection "White BG" no longer exists. New plot mode: Both lines and points for same data set. New feature: The Custom Plot window allows selection of different plot symbols. If a default plot is selected from the Define Plot window, the symbols are cycled through the data sets. This feature together with plot colours allows 54 distinguishable data sets to be plotted. New feature: The conversion module to change to the Draw format has been recoded. It is now faster, smaller, requires less memory, and provides line colours. New feature: Menu selection to call palette for selection of screen colours. Palette may be saved. New feature: The ZOOM out feature to reduce the size of the plot now obtains the "double click" timing from preferences. New feature: The loading of a default palette on starting. Palette data is stored in a file called "MPlot.def" in either the same directory as Multiplot, or in the s: directory. New feature: The number of X and Y axis tick marks or lines can now be defined independently. New feature: Multiplot now uses overdimensional screens. An attempt is made to open and use a screen the same size as workbench. This will give those with multisync monitors and the Morerows patch some more real estate to play with. The screen size can be forced to standard if needed. New feature: Data file format is checked before loading. Loading status is displayed in screen title bar. New feature: The data file may now contain carriage returns at the ends of lines. This allows data to be imported from spreadsheets which are IBM file compatible. New feature: All error reports are relayed via alerts or requesters. No error messages will appear in the current CLI. New feature: Lines in the data file which begin with "*SCALFACT*" may contain scale factors by which collected data is to be multiplied. The scale factor columns map to data columns after the keyword "*SCALFACT*" is discarded. New feature: Title, X axis label and Y axis labels are now printed. They may be defined in the data file by using the *Title*, *XLabel* and *YLabel* keywords. Note that although the Y axis label appears on screen as vertical text, on the printed output, it is written sideways. New feature: It is now possible to quit from the Data Selection Window. This is necessary if a suitable file to plot cannot be found. New feature: The Custom Plot window now has a STOP button. If used when defining plot options for the first time, all remaining data sets will be skipped and not plotted. If the plot options are being described after calling Redefine Plot from the menu bar in the Plot window, this button will redraw the plot without changing the options for the remaining data sets. Other Improvements: Many functions have been optimised to use less memory and run faster. HISTORY Multiplot was originally written by Tim Mooney as a plotting utility for use with mCAD, his freeware CAD program. It supported a flexible input textfile format, many plotting options, and HPGL plotter output. It was not an intuitive program, and its full power was difficult to realize. It was also very limited in output formats and had no support for printers. Some of these problems were addressed in PLOT, an intuition interface which created an environment from which Multiplot and a collection on conversion files could be called. However the major problem of a non-intuitive way of selecting plotting options remained (the "How to Plot" window), and it was not possible to print output from within the program. Multiplot XLN resolves these problems. SUMMARY Multiplot XLN is a fully intuitive data plotting program. It plots data points as (x,y) coordinates with or without error bars. It can plot multiple sets of data points using colour or point size to represent the deferent sets. A set may be joined by a line or plotted as discrete points. The input file for multiplot is a simple textfile and my be created in the NotePad. Output may be in any of the following formats: IntroCAD, Draw, mCAD, IFF, HPGL. The graph can be printed to any workbench printer by transparent use of the PLT: device. REQUIREMENTS Workbench 1.3 (or higher) containing: Maths libraries The C: directory must contain the files c:run, c:failat and c:mount. The PLT: device consisting of: Plt-handler in the l: directory The mountlist entry for plt added to the devs:mountlist At least 1Mb RAM. The files Multiplot, txt_2_icad and plot2draw must be kept together in the same directory. Text on screen currently uses Times.font sizes 14 and 24 point. If these fonts are absent, the default font will be used. INPUT FILE FORMAT Multiplot accepts a simple ASCII file for input of data. The data must consist of columns of numbers. Text heading the file will be ignored with the exception of lines beginning with: *TITLE* Text will be used for a title. *XLABEL* Text will be used for a label on X axis. *YLABEL* Text will be used for a label on Y axis. *SCALFACT* The numbers following will be multiplied to data in the respective columns. Blank lines or lines of text interrupting the columns of numbers are interpreted as separating sets of data, and each set will be plotted individually in, for example, a different colour or point size. See "plotme.dat" or "eric.dat" for examples of input file format. STARTING OUT From the CLI: > multiplot [-O] [filename] Type 'multiplot' with or without the filename of the input data file. If a '?' is used as an argument, a simple description of usage is given. The '-O' option will prevent an overscan screen being opened. This option will have no effect if you are not using an overdimensional workbench. From the Workbench: Double click on the Multiplot icon OR Edit your input file in a simple editor (NotePad will do fine), and save with an icon. You can then change the file's default tool (INFO from the left hand Workbench menu) to Multiplot:Multiplot or whatever the file path is. Multiplot will then be automatically invoked when the file is double clicked. An alternative to this is to not change the file's default tool, but to click on the file to highlight it hold the shift key down, and then double click on the Multiplot icon. It doesn't matter if you get them around the wrong way. OVERSCAN SCREENS If you are using an overscan work bench (via MoreRows or some other trickery) Multiplot will attempt to open a screen the same size as your workbench screen. This enables you to make the most of the resolution of you monitor. The default to overscan can be prevented in three ways: 1) Use a standard Workbench. 2) If starting from the CLI, use the -O option as the first argument. 3) If starting from the workbench, set the TOOLTYPES string in the info requester for the Multiplot icon to "OVERSCAN=OFF" (without the quotes). THE DATA SELECTION WINDOW After being started, Multiplot tries to work out whether it is on a PAL or NTSC machine, and opens a screen of the appropriate size. If an overscan workbench is used, a screen as large as possible up to the size of the workbench screen will be opened. The screen's palette is read from the file "MPlot.def" which should be in either the same directory as Multiplot or the s: directory. If it is not found, you will be informed and a screen the colour of vomit will be opened. This should encourage you to save a new default palette! The next thing you see is the DATA SELECTION WINDOW. If you started Multiplot by telling it what file you wanted to plot, the file's name will be in a little box. If Multiplot is invoked without telling it what file you want, the default file name will appear in the box. The PATH button will call up a file requester to help with browsing directory trees looking for wanted data files. Beneath the file selection box are three other boxes to indicate what column the X, Y and Error values are in. A '0' indicates values are absent. For example if the Error box has a '0', no error bars will be plotted. If the X box has a '0', the X values will be assumed to start at 0 and increase by 1 with each data point. When satisfied with the file and column specification, hit the return key or click on the Continue=> arrow. The selected data file will be checked to ensure it has the number of columns required, and loaded if suitable. THE DEFINE PLOT WINDOW The DEFINE PLOT window is the first level of choosing plot options. In this window you may turn the error bars on (if available) or off, turn a cross grid on of off, and choose the number of tic marks along the X and Y axes. You can also choose to have the data plotted in either default points (all sets plotted as points, each in a different colour and plot type), lines or both. If you wish to specify plotting options for each data set individually, click off the Default Plot button. Hit the Continue=> button when happy with your selections. If a default plot was chosen, you will pass straight to the PLOT window. If not the next window is the CUSTOM PLOT window. THE CUSTOM PLOT WINDOW This is the next level in choosing plot options. For each data set for plotting, this window will appear to allow you to select plot colours and whether data is plotted as a line, series of points or both. If points are drawn, the point size and point type can be selected. The Continue button will accept changes and proceed to the Plot window where the plot is rendered. The SKIP button will skip a single data set, so that it will not be plotted when the Plot window is opened. The function of the STOP button depends on whether the Custom Plot Window has been called when plotting the data for the first time or not. If the Custom Plot Window was reached by loading a data file, and passing through "Define Plot", the STOP button will skip all remaining data sets without plotting them. This is useful for visualising the first few sets without having to push the SKIP button for each data set. If the Custom Plot Window was reached by selecting the Redefine Plot menu option from the Plot Window, the STOP button will redraw all the remaining data sets with the same options used in the previous plot. This enables the alteration of the plotting options of a few data sets without having to reset all the data sets. THE PLOT WINDOW The PLOT window fills the entire high resolution screen and contains a hand crafted menu for your computing pleasure. The menus available are PROJECT which relates to the loading, saving and printing or plots, EDIT which allows modification of the plot, resizing, shifting and zoom, and the OPTIONS menu which changes the screen palette, turns the axes, grid and cross hair on or off and returns you to the DEFINE PLOT window. The major menu items are described below. NEW Returns you to the DATA SELECTION window for loading a new file. You will NOT be prompted by a requester asking if you really REALLY want to restart. This is because 1) You almost certainly do, and 2) You don't actually loose very much even if you don't. SAVE Plots may be saved in any of the following formats: IFF (loads into DPaint), Draw (loads into Draw2000 etc), IntroCAD (an excellent CAD program), mCAD (a PD CAD program), and HPGL plotter language. Please note the following restrictions: Currently Draw, IntroCAD, and mCAD saves do not include the numbers or labels on axes. You will need to jot these down when saving in these formats. Draw saves require the program Plot2Draw to be in the same directory as Multiplot. IntroCAD saves require the program Txt_2_Icad to be in the same directory as Multiplot. Please Note: # Neither Professional Page nor PageStream handle Draw files with large dimensions very well. If your dimensions are greater than 200 units, these programs often scramble the data. Rescale your data to keep within these limits if you wish to import to either of these programs. Data may be rescaled by adding a line to the data file which begins with "*SCALFACT*" and contains scale factors by which data following is to be multiplied. Scale factor columns map to data columns after the keyword "*SCALFACT*" is discarded. # mCAD does not handle plots with small dimensions very well. If your data is in hundredths of units, mCAD will not plot anything on the screen. This can be corrected by using *SCALFACT* to rescale data. # CAD file formats are very poorly optimised. As a result, saves of large plots may take a long time. PRINT Printing is achieved via the transparent use of the PLT: device. The plt-handler must be in your l: directory, and the PLT: mountlist must be added to your DEVS:mountlist. You do not need to mount the device. Multiplot will mount PLT: automatically if it is not already mounted. Notes on use of Plt: # Plt: opens its own window on the workbench when it starts up. This window relays information about how much of the image has been printed and the remaining system memory. It also provides a "close gadget" (The square with a dot in it for closing windows) which will abort the print. Use the left-Amiga-M and left-Amiga-N key combinations to switch between Multiplot's screen and the workbench. # Multiplot checks for the presence of the Plt-handler in the L: directory before attempting to mount Plt:. If this file is not present, Multiplot will not print, even if the Plt: device has been mounted by some other mechanism. QUIT Quit does the obvious, with the same restrictions noted in the section on NEW. ZOOM Allows closeup views of areas of the data, and to adjust the axes to desired values. After selecting ZOOM from the menu, the mouse may be used to draw a box on the screen to indicate the area of the plot to be enlarged. This is achieved by clicking and holding the left mouse button, dragging the mouse, and releasing the left mouse button. The maximum limit of enlargement is 1,600 times. Zooming out to reduce the size of the plot by one half is achieved by double clicking the left mouse button. SLIDE After selection the mouse may be used to draw a vector on the screen to indicate the direction and amount the plot should be moved. This is achieved by clicking and holding the left mouse button, dragging the mouse, and releasing the left mouse button. LOCKS Allows either the X or Y dimension to be frozen while the other is zoomed or rescaled. very useful when used in conjunction with the other items in this menu (Zoom, Slide, FullPlot). This allows you to arrange the scale of the plot to best advantage. The Subitem X AXIS will lock the amount of zoom in the X axis, and the subitem name will change to "X LOCK ON". The lock may be turned off by reselecting the subitem. The same applies for the Y AXIS selection. the X & Y AXIS selection will lock both axes. They will have to be unlocked individually. REDRAW Redraws the screen with the same zoom as currently set. This is different from FULLPLOT and REDEFINE PLOT which will reset to either the full plot, or if the X or Y locks are on, to the locked plot size. REDEFINE PLOT Returns you to the DEFINE PLOT window to alter settings described above. This is destructive in the sense that any zooming that has not been locked will be lost. CROSS HAIR Provides a cross hair for the cursor to assist with zooming and sliding. GRID Turns the grid on and off without having to return to the DEFINE PLOT window. AXES Turns the axes and labels off and on. PALETTE The screen palette may be altered by calling the neat requester, which was written by RJ. The only non obvious feature of the requester is that by clicking the left mouse button on the RGB characters, the requester is converted to a hue/saturation/lightness requester for those who think that way. The SAVE Subitem will attempt to write a file called MPlot.def to the same directory as Multiplot, or failing that, to the s: directory. This file is in the same format as the screen palette files produced by the program "Colour" by a nationalistic Canadian bloke. TUTORIAL This section contains step by step instructions for producing the graph in the plotme.pic file which may be visualised by loading into DPaint or any IFF viewer. Aim: To load a .dat file for plotting. Method: Double click on the Multiplot icon. The filename in the file selection window is [path]/multiplot.dat. Click the left mouse button with the pointer in the lowest numerical box which is to the right of text reading "Error in Y is in Column". Delete the '0' and type in a '3'. Click the left mouse button with the pointer over the Continue=> button. Aim: To access the Custom Plot selections. Method: Click the left mouse button with the pointer over the box with a big tick in it. The tick should change to a cross. Click the left mouse button with the pointer over the Continue=> button. Aim: To select custom selections for plots. Method: Click the left mouse button with the pointer over the box with the word 'default' in it. Keep clicking the left mouse button to select the colour desired for the first data set. Click the left mouse button with the pointer over the box with the word 'line' in it. The word should change to 'point'. Click the left mouse button with the pointer in the lower, numerical box with the number '6' in it. Delete the number '6' and replace it with the number '10'. Click the left mouse button with the pointer over the box on the right hand area with an asterix (looks like *) in it. The box should change colour. Click the left mouse button with the pointer over the Continue=> button. The Custom Plot window should disappear, and then reappear. It should now have the words "Second Data Set" at the top. Change the colour of the Colour box as before, and select a new plot symbol from the choice in the Point Type box. Click the left mouse button with the pointer over the Continue=> button. The Custom Plot window should disappear, and then reappear. It should now have the words "Third Data Set" at the top. Change the colour of the Colour box as before, clicking on the coloured area until the word 'default' is seen, and then once more, to select the colour Black. Click the left mouse button with the pointer over the box with the word 'point' in it. The word should change to 'both'. Click once more. The word should change to 'line' again. Click the left mouse button with the pointer over the Continue=> button. The Custom Plot window should disappear, and then reappear. It should now have the words "Forth Data Set" at the top. Click the Continue=> button once more. The Plot should be rendered on the screen. Aim: To save the plot in the IFF format so that it can be used in DPaint. Method: Hold down the right mouse button, and push the pointer up to the top of the screen. A bar with writing on it should appear. Push the pointer over to the left hand end, all the while holding down the right mouse button. A list of words should drop down from the word 'Project' at the top. Drag the pointer down the list to the word 'save', all the while holding down the right mouse button. Another list of words should appear to the right of the pointer. Move the pointer over the list, all the while holding down the right mouse button. Release the right mouse button over the word 'IFF'. A window should appear to let you choose where to save the picture. Click the left mouse button in the strip at the top of the window. Type the word "RAM:" with the colon (looks like :) but not the quote marks. Click the left mouse button over the word 'OK' at the bottom left of the window. The pointer should turn into the sleepy balloon that means the computer is busy. After 25 seconds the pointer should return. Select the Exit option from the Project menu by holding down the right mouse button, sliding and releasing it as before. The picture will be saved as a file on your RAM disk, and can be moved to another disk on the workbench by dragging its icon. THE FUTURE Probable enhancements to come are: intuitive text addition and editing with definable on screen fonts, saved output of screen text, step and bar graphs. Suggestions welcomed. BETA TESTERS WANTED If you would like to see the latest version of Multiplot, why not volunteer as a beta tester? Send disk and return address to the address below. CONCLUSION Multiplot is the first intuitive Data plotting program for the Amiga. It allows extremely rapid visualisation of experimental data with a wide selection of output formats. It does a simple job, but does it well. If you have suggestions, questions, bug finds, please write: Dr Alan G Baxter, Walter & Eliza Hall Institute, c/o Post Office, Royal Melbourne Hospital, Parkville 3053, AUSTRALIA Thanks to Tim Mooney for the great code, and Graeme Riddle for testing.